
                         R o c k N E S
                    A NES videogame emulator
                       (c)1998-2008 Fx3
                   Win32 version 5.00 beta 14
                       November 9th 2008

  Freeware, for home use
  http://rocknes.kinox.org
  http://rocknes.phpbbnow.com
  <<======================================================================>>

   LICENSE AGREEMENT:

   - This is free software, for home use only.
   - No warranties, so you take the risk. 
   - ROM images cannot be distributed with this software.
   - Please, don't bother me if you messed up the things, ok?
   * If you disagree with these terms, DELETE THIS SOFTWARE NOW.

   MINIMAL PC HARDWARE:

   - The NES emulation uses cycle precision, pixel by pixel rendering.
   - You need a 1GHz CPU processor. RockNES isn't aimed for old machines.
  --------------------------------------------------------------------------
    ----------------------------------------------------------------------  

** NOTICE ** This is beta version (unstable or buggy).

 What's new for version 5.00 beta 14 (11/09/2008)
 ------------------------------------------------
 - Added triple buffering, no screen tearing.
 - Usual fixes and minor GUI changes.

 [==========================================================================]
   Read 'oldnews.txt' for a complete history of updates.
 [==========================================================================]

 1. Description
 2. Configurations and default controls
 3. Using the GUI + Game Genie.
 4. iNES file format description.
 5. VS Unisystem games.
 6. "What is a NES mapper?"

 [==========================================================================]
   KNOWN EMULATION ISSUES

 - The game Time Lord is glitched. Press F5 to reset and it should work fine.
 - Mapper 4 (MMC3) has no IRQ emulation, so a lot of games will be glitched.
 - Press ENTER during the emulation if the ESC key (for GUI access) looks blind.
 - Depending of your sound settings, expect some hicups.
 - Due to the sprite render rewrite, some games can flicker for some reason.
 - Mappers 9 and 10 are glitched in the right side of the screen.
 - The game Battletoads (mapper 7) can freeze during the stage 2.

 [==========================================================================]

 1. Description
 --------------

 > This software emulates the Nintendo Entertainment System videogame,
known as NES.
 > RockNES is fully coded in C, and it uses the Allegro library for audio,
video and inputs.

 * Emulated hardware features *

   - NTSC NES, the RP2AO3 chip contains the CPU and APU, based on the 65O2 processor.
   - NTSC NES PPU, or Picture Processing Unit.
   - NES APU, the audio processing unit which generates sound for games.
   - Controller ports (joypads 1 and 2).
   - Konami's VRC6 sound chip used like in Akumajou Densetsu.
   - VS-Unisystem is partially emulated, iNES format only.
   - Backed battery.
   - Supported iNES mappers 0,1,2,3,4,7,9,10,11,13,15,16,18,19,20,21,22,23,24,
   25,26,32,33,34,40,41,42,43,44,57,64,65,66,67,68,69,70,71,72,73,75,76,78,79,
   83,85,88,90,91,92,94,97,99,100,101,110,113,117,118,119,151,160,180,184,187,
   189,225,226,227,228,229,230,231,232,233,234,235,240,243,246 and 255.

 NOTES: 1. Famicom DiskSystem emulation (mapper 20) requires the BIOS file
        named 'disksys.rom'.
        2. RockNES uses a custom RGB palette taken from Rockman Complete Works,
        and a few holes filled up using Chris Covell's palette as reference.
        3. I have no interest of emulating mapper #5 (MMC5, CastleVania 3).
        4. The PPU rendering needs a fix in order to match the NES procedure.

   > Other features available:
   ---------------------------
    - PPU color emphasis and monochrome mode.
    - Joypad data logging, for game replays.
    - Savestates.
    - NESticle savestate loading (.STA files).
    - Trainer data, hacked RAWs.
    - GUI and config file.
    - Game Genie codes.
    - PRG ROM data patching.
    - Sound recording in WAV format.
    - FUll PRG ROM disassembler.
    - Stereo sound.
    - Image blitter at 640x480 (normal or scanlined).
    - Image blitter at 512x480 (normal, pixelated or scanlined).

 * Unemulated hardware *

 - Unofficial CPU opcodes.
 - The Famicom Computer and the european PAL.
 - Zapper (light gun), Power Pad and others.
 - Joypads 3 and 4.
 - VS-Dualsystem.
 - Playchoice-10 upper monitor (z80 emulation).
 - More custom sound chips.

 NOTES: 1. There is ZIP file support.
        2. For the first run, RockNES creates a config file rocknes.ini within a lot of options.
           Use any text editor and have fun. You can configure it using the GUI too.
 
 [==========================================================================]

 2. Player controls
    Hot keys
 ------------------

 > Player controls:

    [player 1] - device is KEYBOARD
    UP, DOWN, LEFT, RIGHT  = keyboard arrows
    A      = 'X' key
    B      = 'Z' key
    SELECT = 'Tab' key
    START  = 'Enter' key

    [player 2] - no device assigned (KEYBOARD)
    UP     = 'U' key.
    DOWN   = 'J' key.
    LEFT   = 'H' key.
    RIGHT  = 'K' key.
    A      = 'S' key.
    B      = 'A' key.
    SELECT = 'Q' key.
    START  = 'W' key.

    > Joystick:

    UP,DOWN,LEFT,RIGHT = D-pad
    A      - button 1
    B      - button 2
    SELECT - button 3
    START  - button 4
    Quit Emulator - button 5
    Fast Forward  - button 6

 > Hot keys (cannot be remapped):

 <ESC> - calls/quits the GUI.

 <F1>  - toggles Frames-Per-Second (FPS) display.
 <F2>  - save state to selected slot
 <F3>  - slot selector (0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F)
 <F4>  - load state from selected slot

 <F5>  - reset
 <F6>  - FDS disk side flip (A->B->C->D->A...)
 <F7>  - FDS disk insert/eject
 <F8>  - insert coin (VS Unisystem only)

 <F9>  - gameplay logging, or NES movies.
 <F10> - gameplay replay.

 <F12> - take screenshot

 [==========================================================================]

 3. Using the GUI
    NES memory overview
    Additional notes
    Game Genie
    Triple buffering
 -----------------------------

 > Here's a quick summary of the GUI. The menubar is composed by the items:

       [ File  CPU  Misc  Options  Help ]

 [Main]
  - Load ROM...........: File selector, valid extensions are NES,NEZ,FDS,BAK,ZIP.
  - Game info..........: Displays iNES header information + CRCs.
  - Take screenshot....: The gameplay image is saved as bitmap (BMP).
  - Sound recorder.....: Record WAV files.
  - Quit...............: Close the emulator program.

 [CPU]
  - Reset..............: Performs a reset.
  - Hard reset.........: Same of powering off, then power on and reset.
  - Save state.........: Savestates, can freeze your gameplay progress.
  - Load state.........: Loads savestates, up to 16 slots are available.
  - Load NESticle state: Loads a NESticle emulator savestate.
  - Dump... ...........: NES memory dumping, already explained.
  - View ASM source....: The 65O2 program code disassembled.
  - Manual disassembler: You can disassemble any CPU address.

 [Misc]
  - Video resolution...: You can change the video driver and the resolution.
  - Movies.............: Your gameplay can be reproduced later.
  - Palettes...........: Changes the actual palette, for VS Unisystem games.
  - ROM cheat..........: You can patch a certain ROM address.
  - Game Genie.........: GameGenie codes.
  - ROM Corruptor!.....: Corrupts a certain CPU memory range.

 [Options]
  - Input setup........: Select the input device, as keyboard or joypads.
  - Sound config.......: Changes the sound quality and stereo/mono modes.
  - Directories........: You can configure the paths for dumps and more.
  - Frame blitter......: Choose a blitter, it enhances your game image.

 [Help]
  - System.............: Displays some important system information.
  - About... ..........: Software version.

        <<--------------------------------------------------------->>
          NES memory overview

          [CPU] 
          $0000-$1FFF: system RAM, main block at $0000-$07FF, mirrored 8 times.
          $2000-$2007: PPU registers, mirrored through $2008-$3FFF.
          $4000-$4017: APU registers.
          $4018-$5FFF: Used by memory mappers.
          $6000-$7FFF: Backed battery or used by memory mappers.
          $8000-$FFFF: PRG ROM banks of 16k each.

          [PPU]
          $0000-$1FFF: CHR RAM, divided into 2 pattern tables of 4k each.
          $2000-$3EFF: Name tables, divided into 4 banks of 1k each.
          $3F00-$3F1F: Palette RAM, but they're palette indexes, not RGB values.
          $3F20-$3FFF: Palette RAM mirrors.
          $4000-$FFFF: Mirrors of $0000-$3FFF.
        <<--------------------------------------------------------->>

 > For debugging purposes, you can analyse the NES emulation context using the
 dump option in the CPU menu:


 # [menubar] CPU -> Dump... -> "RAM            "
                               "CPU $6000-$7FFF"
                               ----------------- 
                               "CPU $8000-$FFFF"
                               "CPU context    "
                               ----------------- 
                               "PRG ROM        "
                               "CHR ROM        "
                               ----------------- 
                               "Palette RAM    "
                               "Pattern tables "
                               "Name tables    "
                               "Sprite RAM     "

    +---------------------+------------------+---------------+
    | context             | CPU memory range | filename      |
    +---------------------+------------------+---------------+
    | RAM                 | $0000-$1FFF      | nes_ram.bin   |
    | Save RAM            | $6000-$7FFF      | nes_wram.bin  |
    +---------------------+------------------+---------------+
    | Main 32k PRG        | $8000-$FFFF      | <gamename>.bin|
    | CPU registers       | $0000-$FFFF      | cpu65O2.txt   |
    +---------------------+------------------+---------------+
    | PRG ROM             | $4020-FFFF       | <gamename>.prg|
    | CHR ROM             | $4020-FFFF       | <gamename>.chr|
    +---------------------+------------------+---------------+
    * RAM at 0000-07FF is mirrored 8 times through $0800-$1FFF.
    * Usually, the games use $6000-$7FFF for backed battery data.
    # The PRG banks switched at 8000h-FFFFh are dumped.
    # The CPU context saved is:
      - Interrupt vectors (NMI/RESET/IRQ).
      - Registers A, X, Y, S, P.
      - Program counter (PC).
      - IRQ and NMI pending flags.
      - $6000-$7FFF state, as ROM, SaveRAM or open bus.
      - $8000-$FFFF state, as ROM or open bus.
    % The RAW data of PRG ROM banks is dumped.
    % The RAW data of CHR ROM banks is dumped.

    +---------------------+------------------+---------------+
    | context             | PPU memory range | filename      |
    +---------------------+------------------+---------------+
    | Pattern tables      | 0000h-1FFFh      | <gamename>.chr|
    | Name tables         | 2000h-3EFFh      | <gamename>.nam|
    | Palette RAM         | 3F00h-3FFFh      | pal_ram.bin   |
    | Sprite RAM          | I/O at 2004/4014h| sprites.bin   |
    +---------------------+------------------+---------------+

        <<--------------------------------------------------------->>
          Additional notes

 - The selectable inputs are keyboard (setup 1 or 2), joysticks or mouse.
 - The mouse support for gameplay is very poor and must be used only as 
curiosity; don't expect superb gameplay. Press key 'Q' to quit the emulator.
 - All the changes are saved into rocknes.ini file when you close the emulator.
 - When you modify the sound config, it requires the emulator to be restarted.
Changes will take effect on next launch.

 - The NES movies do NOT represent a multimedia file, like an AVI, MPEG or other
kind of video. What's called "movie" here is the ability to replay a game by
reading all your keypresses saved during the normal gameplay. Files .rmv are 
the saved gameplays, known here as "NES movies".

        <<--------------------------------------------------------->>
          Game Genie

 - Game Genie codes are supported, but I can't confirm a fully working support.
Why don't you try out and send me some feedback? ;)

 > GameGenie codes can be either 6 or 8 digits and use the letters:
    A P Z L G I T Y   E O X U K S V N

// To test game genie 6 char code - SXIOPO    Super Mario 1  Unlimited lives
// To test game genie 8 char code - SXEZSKOZ  Super Mario 3  Skywalker

 > To input a GameGenie code, go to Misc->Game Genie. A small window will
 appear requesting a code, disregarding case (SXEZSKOZ, SxEzSKoz or szezskoz
 are acceptable). Any invalid letter is ignored. Click OK to finish or CLEAR
 to delete all inserted codes.
 > No way to enable/disable a code during gameplay. For 6 chars codes only,
 you must reset the emulation to take effect.

 Note for advanced users:

 > A 6-char GG code will patch data at 8000h-FFFFh on reset only. If a game
 uses bankswitch, there are chances to get an useless code. The 8-char code
 has no problem - it keeps patching whatever appears there.

        <<--------------------------------------------------------->>
          Triple buffering

 - By request, triple buffering is available now! It eliminates the screen
tearing effect, making your gameplay smooth during the screen scrolling.
 - However, triple buffering only works on full screen modes, as far as I
know.
 - To enable it, you select in the GUI "Options" -> "Frame blitter", and pay
attention to the 2 new options after the blitters. Select "Triple buffering"
and hit the "X" buttom. Changes will take effect on next launch.
 - You can edit the rocknes.ini config file and change -triple_buffering to 1.

 [==========================================================================]

 4. iNES header format
 ---------------------

 > RockNES supports only RAW files with iNES header, created by Marat
 Fayzullin. Here's the format description:

    +--------+------+------------------------------------------+
    | Offset | Size | Content(s)                               |
    +--------+------+------------------------------------------+
    |   0    |  3   | NES                                      |
    |   3    |  1   | $1A                                      |
    |   4    |  1   | 16K PRG ROM banks                        |
    |   5    |  1   | 8K CHR ROM banks                         |
    |   6    |  1   | RAW control lower byte                   |
    |        |      |   %mmmmvTsM                              |
    |        |      |    |  ||||+- 0=Horizontal Mirroring      |
    |        |      |    |  ||||   1=Vertical Mirroring        |
    |        |      |    |  |||+-- 1=Backed battery            |
    |        |      |    |  ||+--- 1=Trainer data (512 bytes)  |
    |        |      |    |  |+---- 1=Four screen mirroring     |
    |        |      |    +--+----- Mapper # (lower 4-bits)     |
    |   7    |  1   | RAW control upper byte                   |
    |        |      |   %MMMM00PU                              |
    |        |      |    |  |  |+- 1=VS Unisystem arcade       |
    |        |      |    |  |  +-- 1=Playchoice-10 arcade      |
    |        |      |    +--+----- Mapper # (upper 4-bits)     |
    |  8-15  |  8   | Reserved, must be zeroes.                |
    +--------+------+------------------------------------------+

 * RAW stands for the PRG and CHR ROM banks only.
 * If four screen mirroring flag is set, then the horizontal/vertical is ignored.
 * PRG-ROM stands for PRoGram ROM, or 65O2 CPU instructions.
 * CHR-ROM stands for CHaRacter ROM, or game graphics.

 > Be sure you're loading a RAW data with a valid iNES header.
 > Mappers greater than 255 are not supported.
 > The file size must match the size specified by the number of PRG/CHR pages.
 > There's no direct emulation of specific cartridge boards, but only iNES mappers.

 [==========================================================================]

 5. VS Unisystem
 ---------------

 > The Nintendo VS Series was a series of arcade video games designed for two-player
 competitive play using the VS. UniSystem or VS. DualSystem, arcade system boards 
 based on the Nintendo Entertainment System. Many of these stand-up or sit-down arcade
 machines had two screens and controls joined at an angle.
 > These games were arcade ports of home video games for the Nintendo Entertainment 
 System, thus they could be sold cheaply to arcades in the late 1980s.

 Source: WikiPedia
  http://en.wikipedia.org/wiki/Nintendo_Vs._Series

 * DIP Switches are not supported.

 [==========================================================================]
 
 6. The PRG ROM disassembler
 ---------------------------

 > RockNES has a good PRG ROM disassembler. You have two great options, selectable from 
 [Menubar]-> CPU-> View ASM source, or [Menubar]-> CPU-> Manual disassembler.

 [1] "View ASM source" - overview

 +-----------------------------------+
 |$8057 *A=90, X=05, Y=00, S=FF, P=A5|  -> PC value, registers A,X,Y,S,P.
 |PRG bank 00 [ROM=$00057]           |  -> PRG ROM bank paged at $x000
 |+---------------------------------+|    (x = 5,6,7,8,9,A,b,C,D,E or F)
 ||8000 78       SEI                || 
 ||8001 D8       CLD                ||
 ||8002 A9 10    LDA #$10           || 
 ||8004 8D 00 20 STA $2000          ||
 ||8007 A2 FF    LDX #$FF           ||
 ||8009 9A       TXS                ||
 ||800A AD 02 20 LDA $2002          ||  -> Program code, 65O2.
 ||800D 10 FB    BPL $800A          ||
 ||800F AD 02 20 LDA $2002          ||
 ||8012 10 FB    BPL $800F          ||
 ||8014 A0 FE    LDY #$FE           ||
 ||8016 A2 05    LDX #$05           ||
 ||8018 BD D7 07 LDA $07D7, X       ||
 ||801B C9 0A    CMP #$0A           ||
 ||801D B0 0C    BCS $802B          ||
 ||801F CA       DEX                ||
 |+---------------------------------+|
 |( )$5000( )$6000 ( )$7000          |  -> CPU address select
 |(o)$8000( )$9000 ( )$A000 ( )$B000 |
 |( )$C000( )$D000 ( )$E000 ( )$F000 |
 +-----------------------------------+

 > You can choose a CPU address. If you select $8000, the entire ROM bank
 at $8000-$8FFF is disassembled. Push "REFRESH" button.
 > This is for "read-only", as you're unable to modify any value from here.
 It's good to detect bankswitch errors (invalid banks) or CPU hangs.
 > The code above is a sample of Super Mario Bros. code.

 [2] "Manual disassembler" - overview

 +---------------------------------------------------+
 | Manual disassembler                               |
 | Please, input a proper address:                   |
 |                                                   |
 |  8000___ [Refresh] (o)CPU  ( )ROM    [Save]       |
 |                                                   |
 |+---------------------------------+ +------------+ |
 ||8000 78       SEI                | |PC=$8057    | |
 ||8001 D8       CLD                | |A=$90       | |
 ||8002 A9 10    LDA #$10           | |X=$05       | |
 ||8004 8D 00 20 STA $2000          | |Y=$00       | |
 ||8007 A2 FF    LDX #$FF           | |S=$FF       | |
 ||8009 9A       TXS                | |P=$A5       | |
 ||800A AD 02 20 LDA $2002          | |            | |
 ||800D 10 FB    BPL $800A          | |$6000 = $FF | |
 ||800F AD 02 20 LDA $2002          | |$8000 = $00 | |
 ||8012 10 FB    BPL $800F          | |$A000 = $01 | |
 ||8014 A0 FE    LDY #$FE           | |$C000 = $02 | |
 ||8016 A2 05    LDX #$05           | |$E000 = $03 | |
 ||8018 BD D7 07 LDA $07D7, X       | |            | |
 ||801B C9 0A    CMP #$0A           | |Notice:     | |
 ||801D B0 0C    BCS $802B          | |FF = Open   | |
 ||801F CA       DEX                | |or normal.  | |
 |+---------------------------------+ +------------+ |
 +---------------------------------------------------+

 > It's much like the previous one, with a different layout. the PRG bank
 numbers are disaplyed for all "valid" pages, and FF indicates a possible
 open bus state. You can input any valid address.
 > You're able to specify a CPU offset, from $4020 to $FFFF, or a ROM offset.
 When you click "Refresh", the address specified is disassembled.

 > For *both*, click [SAVE] button to save the disassembled data into a file.
 The ASM code format is: PC value, mnemonics (up to 3 bytes, first one is the
 instruction code, the last 2 are the arguments) and the instruction label and
 address.

 [==========================================================================]

   CREDITS (no special order)
   **************************

 NesDev - NES info, programs and demos
 http://nesdev.parodius.com
 http://nesdevwiki.org

 The Dev-C++ resource site
 http://www.bloodshed.net/dev

 Allegro library, by Shawn Hargreaves
 http://www.talula.demon.co.uk/allegro

 Alastair Bridgewater - Darcnes
 http://www.dridus.com/~nyef/darcnes

 Parodius Networking - website hosting
 http://www.parodius.com

 unzip -- IO for uncompress .zip files using zlib
 Version 1.00, September 10th, 2003
 Copyright (C) 1998-2003 Gilles Vollant

 blargg
 http://www.slack.net/~ant

 Marat Fayzullin
 http://fms.komkon.org

 [=========================================================================]
//eof
